home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 4 / Meeting Pearls Vol. IV (1996)(GTI - Schatztruhe)[!].iso / Pearls / libs / CDPlay / doc / cdplay_library.dok next >
Text File  |  1996-09-19  |  14KB  |  489 lines
  1. TABLE OF CONTENTS
  2.  
  3. cdplay.library/CDClose
  4. cdplay.library/CDCloseDrive
  5. cdplay.library/CDInquiry
  6. cdplay.library/CDJump
  7. cdplay.library/CDLockDrive
  8. cdplay.library/CDNext
  9. cdplay.library/CDOpen
  10. cdplay.library/CDOpenDrive
  11. cdplay.library/CDPause
  12. cdplay.library/CDPlay
  13. cdplay.library/CDPrev
  14. cdplay.library/CDStop
  15. cdplay.library/CDUpdate
  16. cdplay.library/CDClose                                       cdplay.library/CDClose
  17.  
  18.    NAME        
  19.         CDClose -- schließt die Schublade des CDRom Laufwerkes
  20.  
  21.    SYNOPSIS
  22.         result = CDClose (request)
  23.         D0                 A1
  24.  
  25.         ULONG CDClose (struct CDRequest *);
  26.  
  27.    FUNCTION
  28.         Schließt die Schublade des CDRom Laufwerkes.
  29.  
  30.    INPUTS
  31.         request        --        "struct CDRequest *" des entsprechenden        
  32.                         Drives
  33.  
  34.    RESULT
  35.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  36.                         Wert, der dem Errorcode entspricht.
  37.  
  38.    NOTES
  39.         Wird nicht von allen Laufwerken unterstützt
  40.  
  41.    BUGS
  42.         keine bekannt.
  43.  
  44.    SEE ALSO
  45.         cdplay.library/CDOpen()
  46.  
  47. cdplay.library/CDCloseDrive                             cdplay.library/CDCloseDrive
  48.  
  49.    NAME        
  50.         CDCloseDrive -- SCSI Device schließen und Speicher freigeben
  51.  
  52.    SYNOPSIS
  53.         result = CDCloseDrive (request)
  54.         D0                       A1
  55.  
  56.         struct CDRequest *CDCloseDrive (struct CDRequest *);
  57.  
  58.    FUNCTION
  59.         Schließt ein mit CDOpenDrive() geöffnet Device und gibt den benutzten
  60.         Speicher wieder frei.
  61.  
  62.    INPUTS
  63.         request        --        CDRequest des zu schließenden Devices, diese
  64.                         Struktur wird von CDOpenDrive() geliefert.
  65.  
  66.    RESULT
  67.         result        --        Ergebniss des Kommandos, in der Regel muß alles
  68.                         klappen und es wird TRUE geliefert.
  69.  
  70.    EXAMPLE
  71.         siehe cdplay.library/CDOpenDrive()
  72.  
  73.    BUGS
  74.         keine bakannt
  75.  
  76.    SEE ALSO
  77.         cdplay.library/CDOpenDrive(), cdplay.library/CDUpdate(),
  78.         cdplay.library/CDInquiry()
  79.  
  80. cdplay.library/CDInquiry                                   cdplay.library/CDInquiry
  81.  
  82.    NAME        
  83.         CDInquiry -- liest spezifische Informationen aus dem Device aus
  84.  
  85.    SYNOPSIS
  86.         result = CDInquiry (inquiry, request)
  87.         D0                    A0             A1
  88.  
  89.         ULONG CDInquiry (struct CDInquiry *, struct CDRequest *);
  90.  
  91.    FUNCTION
  92.         Liest Informationen aus dem SCSI-Device aus. Dazu gehören unter
  93.         anderen Hersteller und Produkt, Features des Devices, Typ (CDRom,
  94.         Festplatte, ...). Normalerweise wird diese Funktion nur einmal
  95.         pro Device aufgerufen. CDOpenDrive() ruft die Funktion beim Öffnen
  96.         auf, so das der normale Programmierer keine Verwendung haben
  97.         dürfte.
  98.  
  99.    INPUTS
  100.         inquiry        --        "struct CDInquiry *", Struktur die mit den
  101.                         erhätlichen Informationen des Devices ge-
  102.                         füllt wird.
  103.         request        --        "struct CDRequest *", wird von CDOpenDrive()
  104.                         geliefert
  105.  
  106.    RESULT
  107.         result        --        Im Fehlerfall ein von 0 verschiedener Wert
  108.  
  109.    EXAMPLE
  110.  
  111.         struct CDRequest *mycd;
  112.         struct CDInquiry *myinq;
  113.  
  114.         if (mycd = CDOpenDrive ("scsi.device", 2))
  115.         {
  116.                 if (!CDInquiry (myinq, mycd))
  117.                 {
  118.                         /* erfolgreich */
  119.                 }
  120.                 else
  121.                 {
  122.                         /* fehlgeschlagen ;(( */
  123.                 }
  124.  
  125.                 CDCloseDrive (mycd);
  126.         }
  127.  
  128.    NOTES
  129.         Wird normalerweise nie gebraucht.
  130.  
  131.    BUGS
  132.         keine bekannt
  133.  
  134.    SEE ALSO
  135.         cdplay.library/CDOpenDrive(), cdplay.library/CDUpdate()
  136.  
  137. cdplay.library/CDJump                                         cdplay.library/CDJump
  138.  
  139.    NAME        
  140.         CDJump -- springt innerhalb eines Tracks vor/zurück
  141.  
  142.    SYNOPSIS
  143.         result = CDJump (offset, request)
  144.         D0                 D0         A1
  145.  
  146.         ULONG CDJump (LONG, struct CDRequest *);
  147.  
  148.    FUNCTION
  149.         Springt innerhalb eines Tracks zu einer neuen Position. Dabei
  150.         sowohl vorwärts als auch rückwärts gesprungen werden. Der Offset
  151.         gibt dabei die Richtung an (Vorzeichen) und die Sprungweite.
  152.         Ein Wert von 75 entspricht dabei einer Sekunde.
  153.  
  154.    INPUTS
  155.         offset        --        Sprungweite von der aktuellen Position, das
  156.                         Vorzeichen bestimmt die Richtung
  157.         request        --        "struct CDRequest *" des entsprechenden Drives
  158.  
  159.    RESULT
  160.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  161.                         Wert, der dem Errorcode entspricht.
  162.  
  163.    EXAMPLE
  164.         /* .... */
  165.  
  166.         CDJump (-(10 * 75), mycd);        /* 10 Sekunden zurück springen */
  167.         
  168.         /* .... */
  169.  
  170.    BUGS
  171.         keine bekannt.
  172.  
  173. cdplay.library/CDLockDrive                               cdplay.library/CDLockDrive
  174.  
  175.    NAME        
  176.         CDLockDrive -- ermöglicht das Öffnen des CD-Rom´s zu sperren
  177.  
  178.    SYNOPSIS
  179.         result = CDLockDrive (mode, request);
  180.         D0                      D0    A1
  181.  
  182.         ULONG CDLockDrive (ULONG, struct CDRequest *);
  183.  
  184.    FUNCTION
  185.         Ermöglicht es, den Auswurf von CDRom´s zu vermeiden. Mit der
  186.         Funktion kann die Klappe des Laufwerks verriegelt werden
  187.         bzw. eine solche Verriegelung wieder aufgehoben werden.
  188.  
  189.    INPUTS
  190.         mode        --        Einen von 0 verschiedenen Wert zum Verriegeln
  191.                         oder 0, um das Laufwerk freizugeben.
  192.         request        --        "struct CDRequest *" des entsprechenden Drives
  193.  
  194.    RESULT
  195.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  196.                         Wert, der dem Errorcode entspricht.
  197.  
  198.    EXAMPLE
  199.         struct CDRequest *mycd;
  200.  
  201.         if (mycd = CDOpenDrive ("scsi.device", 2))
  202.         {
  203.                 /* Laufwerk verriegeln */
  204.                 CDLockDrive (TRUE, mycd);
  205.  
  206.                 CDCloseDrive (mycd);
  207.         }
  208.  
  209.    NOTES
  210.         Nach einem Reset ist die Verrieglung bei einigen Laufwerken
  211.         aufgehoben, bei anderen nicht. Ausprobieren!
  212.  
  213.    BUGS
  214.         keine bekannt.
  215.  
  216. cdplay.library/CDNext                                         cdplay.library/CDNext
  217.  
  218.    NAME        
  219.         CDNext -- wählt den nächsten Track an
  220.  
  221.    SYNOPSIS
  222.         result = CDNext (request)
  223.         D0                 A1
  224.  
  225.         ULONG CDNext (struct CDRequest *);
  226.  
  227.    FUNCTION
  228.         Springt zum nächsten Track. Wenn es keinen nächsten Track
  229.         gibt, hat der Aufruf keine Wirkung.
  230.  
  231.    INPUTS
  232.         request        --        "struct CDRequest *" des entsprechenden Drives
  233.  
  234.    RESULT
  235.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  236.                         Wert, der dem Errorcode entspricht.
  237.  
  238.    BUGS
  239.         keine bekannt.
  240.  
  241.    SEE ALSO
  242.         cdplay.library/CDPrev()
  243.  
  244. cdplay.library/CDOpen                                         cdplay.library/CDOpen
  245.  
  246.    NAME        
  247.         CDOpen -- öffnet die Schublade des CDRom Laufwerkes
  248.  
  249.    SYNOPSIS
  250.         result = CDOpen (request)
  251.         D0                 A1
  252.  
  253.         ULONG CDOpen (struct CDRequest *);
  254.  
  255.    FUNCTION
  256.         Öffnet die Schublade des CDRom Laufwerkes.
  257.  
  258.    INPUTS
  259.         request        --        "struct CDRequest *" des entsprechenden Drives
  260.  
  261.    RESULT
  262.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  263.                         Wert, der dem Errorcode entspricht.
  264.  
  265.    NOTES
  266.         Wird nicht von allen Laufwerken unterstützt
  267.  
  268.    BUGS
  269.         keine bekannt.
  270.  
  271.    SEE ALSO
  272.         cdplay.library/CDClose()
  273.  
  274. cdplay.library/CDOpenDrive                               cdplay.library/CDOpenDrive
  275.  
  276.    NAME        
  277.         CDOpenDrive -- SCSI Device als Audio-Player initialisieren
  278.  
  279.    SYNOPSIS
  280.         request = CDOpenDrive (device, unit)
  281.         D0                       A0      D0
  282.  
  283.         struct CDRequest *CDOpenDrive (STRPTR, ULONG);
  284.  
  285.    FUNCTION
  286.         Öffnet das SCSI-Device mit der angegebenen Unit und initialisiert
  287.         die CDRequest Struktur mit den nötigen Werten. Diese Funktion kann
  288.         erfolgreich auf alle SCSI-Devices angewendet werden, es muß selbst-
  289.         ständig gecheckt werden, ob das Device ein CD-ROM ist. Das dürfte
  290.         aber kein Problem darstellen, in jeder Programmiersprache sollte
  291.         dieser Test in einer Zeile durchführbar sein. Die Funktion liefert
  292.         im Fehlerfall NULL zurück.
  293.  
  294.    INPUTS
  295.         device        --        Name des SCSI-Devices, z.B. "scsi.device"
  296.         unit        --        Unit, an der das CD-Rom ansprechbar ist, z.B. 2
  297.  
  298.    RESULT
  299.         request        --        "struct CDRequest *", ein Zeiger auf eine
  300.                         CDRequest-Struktur oder NULL im Fehlerfall.
  301.  
  302.    EXAMPLE
  303.  
  304.         struct CDRequest *mycd;
  305.  
  306.         if (mycd = CDOpenDrive ("scsi.device", 2))
  307.         {
  308.                 /* etwas mit dem Laufwerk anstellen */
  309.  
  310.                 CDCloseDrive (mycd);
  311.         }
  312.  
  313.    NOTES
  314.         Diese Funktion kann natürlich von beliebigen Programmen
  315.         benutzt werden und hat nicht unmittelbar mit Audio-CD`s
  316.         zu tun. CDOpenDrive() und CDCloseDrive() können dazu ver-
  317.         wendet werden, Informationen über SCSI-Devices zu bekommen.
  318.  
  319.    BUGS
  320.         keine bekannt, allerdings sollte die Funktion wenn möglich
  321.         MemoryPools nutzen statt mehrere kleine Blöcke zu allokieren,
  322.         das wird in einer der nächsten Versionen geändert.
  323.  
  324.    SEE ALSO
  325.         cdplay.library/CDCloseDrive(), cdplay.library/CDUpdate(),
  326.         cdplay.library/CDInquiry()
  327.  
  328. cdplay.library/CDPause                                       cdplay.library/CDPause
  329.  
  330.    NAME        
  331.         CDPause -- stoppt/startet die Wiedergabe
  332.  
  333.    SYNOPSIS
  334.         result = CDPause (pause, request)
  335.         D0                  D0         A1
  336.  
  337.         ULONG CDPause (ULONG, struct CDRequest *);
  338.  
  339.    FUNCTION
  340.         Mit dieser Funktion kann die Wiedergabe für eine gewünschte
  341.         Zeit angehalten werden, um dann an der selben Stelle wieder
  342.         fortzufahren.
  343.  
  344.    INPUTS
  345.         pause        --        Ein von 0 verschiedener Wert stoppt die Wieder-
  346.                         gabe, 0 selber startet sie, sofern das Lauf-
  347.                         werk vorher aktiv war
  348.         request        --        "struct CDRequest *" des entsprechenden Drives
  349.  
  350.    RESULT
  351.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  352.                         Wert, der dem Errorcode entspricht.
  353.  
  354.    BUGS
  355.         keine bekannt.
  356.  
  357.    SEE ALSO
  358.         cdplay.library/CDStop(), cdplay.library/CDPlay()
  359.  
  360. cdplay.library/CDPlay                                         cdplay.library/CDPlay
  361.  
  362.    NAME        
  363.         CDPlay -- beginnt die Audiowiedergabe eines Tracks
  364.  
  365.    SYNOPSIS
  366.         result = CDPlay (start, request)
  367.         D0                 D0        A1
  368.  
  369.         ULONG CDPlay (ULONG, struct CDRequest *);
  370.  
  371.    FUNCTION
  372.         Beginnt die Wiedergabe eines Audiotracks. Der Starttrack selber
  373.         wird als Parameter übergeben. Die Ausgabe wird erst beendet, wenn
  374.         die ganze CD abgespielt worden ist, eine Funktion wie Pause oder
  375.         Stop gewählt wurde oder die Funktion mit einem neuen Starttrack
  376.         aufgerufen wird.
  377.  
  378.    INPUTS
  379.         start        --        Nummer des Starttracks
  380.         request        --        "struct CDRequest *" des entsprechenden Drives
  381.  
  382.    RESULT
  383.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  384.                         Wert, der dem Errorcode entspricht.
  385.  
  386.    BUGS
  387.         keine bekannt.
  388.  
  389.    SEE ALSO
  390.         cdplay.library/CDStop(), cdplay.library/CDPause()
  391.  
  392. cdplay.library/CDPrev                                         cdplay.library/CDPrev
  393.  
  394.    NAME        
  395.         CDPrev -- wählt den vorherigen Track an
  396.  
  397.    SYNOPSIS
  398.         result = CDPrev (request)
  399.         D0                 A1
  400.  
  401.         ULONG CDPrev (struct CDRequest *);
  402.  
  403.    FUNCTION
  404.         Springt zum vorherigen Track. Wenn es keinen vorhergehenden
  405.         Track gibt, hat der Aufruf keine Wirkung.
  406.  
  407.    INPUTS
  408.         request        --        "struct CDRequest *" des entsprechenden Drives
  409.  
  410.    RESULT
  411.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  412.                         Wert, der dem Errorcode entspricht.
  413.  
  414.    BUGS
  415.         keine bekannt.
  416.  
  417.    SEE ALSO
  418.         cdplay.library/CDNext()
  419.  
  420. cdplay.library/CDStop                                         cdplay.library/CDStop
  421.  
  422.    NAME
  423.         CDStop -- stoppt die Wiedergabe einer Audio-CD
  424.  
  425.    SYNOPSIS
  426.         result = CDStop (request)
  427.         D0                 A1
  428.  
  429.         ULONG CDStop (struct CDRequest *);
  430.  
  431.    FUNCTION
  432.         Stoppt die Wiedergabe einer Audio-CD, die zuvor mit CDPlay()
  433.         gestartet wurde.
  434.  
  435.    INPUTS
  436.         request        --        "struct CDRequest *" des entsprechenden Drives
  437.  
  438.    RESULT
  439.         result        --        liefert im Fehlerfall einen von 0 verschiedenen
  440.                         Wert, der dem Errorcode entspricht.
  441.  
  442.    BUGS
  443.         keine bekannt.
  444.  
  445.    SEE ALSO
  446.         cdplay.library/CDPause(), cdplay.library/CDPlay()
  447.  
  448. cdplay.library/CDUpdate                                     cdplay.library/CDUpdate
  449.  
  450.    NAME        
  451.         CDUpdate -- aktualisiert alle Daten des CDRom´s die im laufenden
  452.                     Betrieb veränderlich sind (z.B. CD-Wechsel)
  453.  
  454.    SYNOPSIS
  455.         result = CDUpdate (request)
  456.         D0                   A1
  457.  
  458.         ULONG CDUpdate (struct CDRequest *);
  459.  
  460.    FUNCTION
  461.         Alle Daten über das SCSI-Device, die sich im laufenden Betrieb
  462.         ändern können (also NICHT Herstellername etc.) werden mit dieser
  463.         Funktion neu ermittelt und im CDRequest abgelegt. Dazu zählen
  464.         Informationen über die CD, aber auch die Position (Zeit) auf der
  465.         CD während des Audioplays.
  466.  
  467.    INPUTS
  468.         request        --        "struct CDRequest *", wird von CDOpenDrive()
  469.                         geliefert
  470.  
  471.    RESULT
  472.         result        --        Fehlercode, der dem Rückgabewert der DoIO()
  473.                         Funktion entspricht. Im Fehlerfall ist dies
  474.                         ein von 0 verschiedener Wert.
  475.  
  476.    NOTES
  477.         Einige Funktionen rufen CDUpdate() von selber auf, ein Aufruf
  478.         ist dann i.d.R. nicht mehr nötig. Zu diesen Funktionen gehören
  479.         cdplay.library/CDJump(), cdplay.library/CDNext() und
  480.         cdplay.library/CDPrev()
  481.  
  482.    BUGS
  483.         keine bekannt
  484.  
  485.    SEE ALSO
  486.         cdplay.library/CDJump(), cdplay.library/CDNext(),
  487.         cdplay.library/CDPrev()
  488.  
  489.